Skip to main content

Configure Forgejo to Mirror a Repository to GitHub

Goal​

Keep Forgejo as the source of truth while automatically mirroring the repository to GitHub so we can use GitHub Actions, particularly Windows runners.

Final setup:

Local Development / VS Code
           │
           │ git push
           ▼
        Forgejo
           │
           │ Push Mirror
           ▼
         GitHub
           │
           ▼
     GitHub Actions
           │
           ▼
      Windows Builds

GitHub should not be used for direct code changes. Development continues normally against Forgejo.

1. Create an Empty GitHub Repository​

Create a new repository on GitHub.

Use the same repository name as Forgejo where possible.

Example:

OneMoreCast

Recommended description:

DO NOT EDIT ON GITHUB, this is used only for Actions. Source of truth is on Forgejo.

Configure:

Visibility:     Private
README:         Off
.gitignore:     No .gitignore
License:        No license

The GitHub repository needs to be completely empty so the existing Forgejo repository can be mirrored into it.

Create the repository.

2. Get the GitHub SSH URL​

After creating the repository, get its SSH URL.

Example:

git@github.com:afrank84/OneMoreCast.git

Do not clone the GitHub repository or run GitHub's initialization commands.

3. Open Forgejo Mirror Settings​

In the existing Forgejo repository, navigate to:

Repository
→ Settings
→ Mirror Settings

Under Push Mirrors, enter the GitHub SSH repository URL:

git@github.com:afrank84/OneMoreCast.git

Leave Branch filter blank.

This allows Forgejo to mirror all branches.

4. Configure SSH Authentication​

Expand:

Authorization

Enable:

☑ Use SSH authentication

Leave the username and password fields blank.

Forgejo will generate a dedicated SSH key pair for this mirror.

Also enable:

☑ Sync when commits are pushed

The configuration should look roughly like:

Git remote repository URL:
git@github.com:afrank84/OneMoreCast.git

Branch filter:
[blank]

Authorization:
Username: [blank]
Password: [blank]

☑ Use SSH authentication
☑ Sync when commits are pushed

Mirror interval:
8h0m0s

The 8-hour interval can remain as a periodic fallback. Sync when commits are pushed causes normal pushes to trigger synchronization without waiting eight hours.

Click:

Add push mirror

5. Copy the Forgejo Public SSH Key​

After creating the mirror, Forgejo will display a Public SSH key for it.

Copy that key.

This is a dedicated key used by Forgejo to authenticate when pushing to GitHub.

6. Add the Key to GitHub​

Open the GitHub repository and navigate to:

Repository
→ Settings
→ Deploy keys
→ Add deploy key

Configure:

Title:
Forgejo Push Mirror

Key:
[paste the public SSH key generated by Forgejo]

Most importantly, enable:

☑ Allow write access

Write access is required because Forgejo needs permission to push commits to the GitHub repository.

Click:

Add key

7. Test the Mirror​

Return to:

Forgejo
→ Repository Settings
→ Mirror Settings

Click the orange Synchronize Now / circular-arrow button next to the push mirror.

Forgejo should push the existing repository to GitHub.

Verify on GitHub that the repository now contains the project files and commit history.

8. Normal Development Workflow​

Nothing changes about the normal development workflow.

Continue using Forgejo:

git add .
git commit -m "Example change"
git push

The flow is now:

git push
   │
   ▼
Forgejo
   │
   │ automatic push mirror
   ▼
GitHub
   │
   ▼
GitHub Actions

There is no need to add GitHub as a second local Git remote or manually push to GitHub.

Important Rule​

Forgejo remains the source of truth.

Do not make code changes directly on GitHub.

Use:

Local Development ↔ Forgejo
                       │
                       └──→ GitHub

Not:

Forgejo ←→ GitHub

GitHub exists as a downstream mirror primarily to provide access to GitHub Actions and Windows runners.

Result​

The repository now automatically mirrors from Forgejo → GitHub whenever commits are pushed, while retaining Forgejo as the primary repository and development workflow.